

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>2. Reference manual &mdash; Documentation of EZ-Draw 1.2</title>
    
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../../share/ez-style-1.2.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '1.2',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="Documentation of EZ-Draw 1.2" href="index.html" />
    <link rel="next" title="3. Installation" href="ez-install.html" />
    <link rel="prev" title="1. Tutorial" href="ez-tutorial.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <span class="current">English</span></li>
        <li class="right">
          <a href="../../fr/html/ez-reference.html">Français</a> |</li>
        <li><a href="../../../index-en.html">EZ-Draw 1.2</a> &raquo;</li>
        <li><a href="ez-manual.html">Documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="reference-manual">
<span id="chap-ref-manual"></span><h1>2. Reference manual<a class="headerlink" href="#reference-manual" title="Permalink to this headline">¶</a></h1>
<p>Sources: <a class="reference external" href="../../../ez-draw.h">ez-draw.h</a>, <a class="reference external" href="../../../ez-draw.c">ez-draw.c</a>.</p>
<div class="section" id="main-loop">
<span id="sec-ref-main-loop"></span><span id="index-0"></span><h2>2.1. Main loop<a class="headerlink" href="#main-loop" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="c.ez_init">
int <tt class="descname">ez_init</tt><big>(</big><big>)</big><a class="headerlink" href="#c.ez_init" title="Permalink to this definition">¶</a></dt>
<dd><p>Initialization.</p>
<p>Return 0 on success, -1 on failure.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_main_loop">
void <tt class="descname">ez_main_loop</tt><big>(</big><big>)</big><a class="headerlink" href="#c.ez_main_loop" title="Permalink to this definition">¶</a></dt>
<dd><p>Main loop.</p>
</dd></dl>

<p>This function displays the existing windows, then waits for events;
for each incoming event the function calls the corresponding window event function
(the <em>callback</em>).</p>
<p>To stop the main loop, call <a class="reference internal" href="#c.ez_quit" title="ez_quit"><tt class="xref c c-func docutils literal"><span class="pre">ez_quit()</span></tt></a> in a callback.
Once returned from <a class="reference internal" href="#c.ez_main_loop" title="ez_main_loop"><tt class="xref c c-func docutils literal"><span class="pre">ez_main_loop()</span></tt></a>, no more graphic call should be done.</p>
<dl class="function">
<dt id="c.ez_quit">
void <tt class="descname">ez_quit</tt><big>(</big><big>)</big><a class="headerlink" href="#c.ez_quit" title="Permalink to this definition">¶</a></dt>
<dd><p>Exit <a class="reference internal" href="#c.ez_main_loop" title="ez_main_loop"><tt class="xref c c-func docutils literal"><span class="pre">ez_main_loop()</span></tt></a>.</p>
</dd></dl>

<span class="target" id="index-1"></span><dl class="function">
<dt id="c.ez_auto_quit">
void <tt class="descname">ez_auto_quit</tt><big>(</big>int<em>&nbsp;val</em><big>)</big><a class="headerlink" href="#c.ez_auto_quit" title="Permalink to this definition">¶</a></dt>
<dd><p>Modify the effect of the &#8220;Close&#8221; button in the title bar of a window,
for each window of the program.</p>
</dd></dl>

<p>By default (<tt class="docutils literal"><span class="pre">val</span> <span class="pre">=</span> <span class="pre">1</span></tt>), if you click on the &#8220;Close&#8221; button of any
window of the program, it ends immediately.</p>
<p>You can change this behavior by invoking <a class="reference internal" href="#c.ez_auto_quit" title="ez_auto_quit"><tt class="xref c c-func docutils literal"><span class="pre">ez_auto_quit()</span></tt></a> with
<tt class="docutils literal"><span class="pre">val</span> <span class="pre">=</span> <span class="pre">0</span></tt> : then, if the user clicks on the &#8220;Close&#8221; button of a window,
the program (instead of ending) will receive the event
<tt class="docutils literal"><span class="pre">WindowClose</span></tt> for this window, so as to decide what to do:</p>
<blockquote>
<div><ul class="simple">
<li>ignore the event;</li>
<li>destroy the window with <a class="reference internal" href="#c.ez_window_destroy" title="ez_window_destroy"><tt class="xref c c-func docutils literal"><span class="pre">ez_window_destroy()</span></tt></a>;</li>
<li>hide the window with <a class="reference internal" href="#c.ez_window_show" title="ez_window_show"><tt class="xref c c-func docutils literal"><span class="pre">ez_window_show()</span></tt></a>;</li>
<li>create a dialog window;</li>
<li>complete the program with <a class="reference internal" href="#c.ez_quit" title="ez_quit"><tt class="xref c c-func docutils literal"><span class="pre">ez_quit()</span></tt></a>;</li>
<li>etc.</li>
</ul>
</div></blockquote>
<p>Note: when all windows are destroyed, the program stops.</p>
</div>
<div class="section" id="windows">
<span id="sec-ref-windows"></span><span id="index-2"></span><h2>2.2. Windows<a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h2>
<p>Each window has a unique identifier, of type <a class="reference internal" href="#c.Ez_window" title="Ez_window"><tt class="xref c c-type docutils literal"><span class="pre">Ez_window</span></tt></a>:</p>
<dl class="type">
<dt id="c.Ez_window">
<tt class="descname">Ez_window</tt><a class="headerlink" href="#c.Ez_window" title="Permalink to this definition">¶</a></dt>
<dd><p>Identifier of a window.</p>
</dd></dl>

<p>The following functions allow to create or manipulate windows:</p>
<span class="target" id="index-3"></span><dl class="function">
<dt id="c.ez_window_create">
<a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a> <tt class="descname">ez_window_create</tt><big>(</big>int<em>&nbsp;w</em>, int<em>&nbsp;h</em>, const char<em>&nbsp;*name</em>, <a class="reference internal" href="#c.Ez_func" title="Ez_func">Ez_func</a><em>&nbsp;on_event</em><big>)</big><a class="headerlink" href="#c.ez_window_create" title="Permalink to this definition">¶</a></dt>
<dd><p>Create and display a window, having width <tt class="docutils literal"><span class="pre">w</span></tt> and height <tt class="docutils literal"><span class="pre">h</span></tt>,
a title <tt class="docutils literal"><span class="pre">name</span></tt>, and a function <tt class="docutils literal"><span class="pre">on_event</span></tt> (the <em>callback</em>) called for each event
(<tt class="docutils literal"><span class="pre">on_event</span></tt> might be <tt class="docutils literal"><span class="pre">NULL</span></tt>).</p>
<p>Return the identifier of the window, of type <a class="reference internal" href="#c.Ez_window" title="Ez_window"><tt class="xref c c-type docutils literal"><span class="pre">Ez_window</span></tt></a>.</p>
</dd></dl>

<p>Any callback has type <a class="reference internal" href="#c.Ez_func" title="Ez_func"><tt class="xref c c-type docutils literal"><span class="pre">Ez_func</span></tt></a> :</p>
<dl class="type">
<dt id="c.Ez_func">
<tt class="descname">Ez_func</tt><a class="headerlink" href="#c.Ez_func" title="Permalink to this definition">¶</a></dt>
<dd><p>The type of a callback, that is to say, the prototype of an event handler,
the function called for each event. This type is defined as:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="nf">void</span> <span class="p">(</span><span class="o">*</span><span class="n">Ez_func</span><span class="p">)(</span><span class="n">Ez_event</span> <span class="o">*</span><span class="n">ev</span><span class="p">);</span>
</pre></div>
</div>
<p>In other words, the function <tt class="docutils literal"><span class="pre">on_event</span></tt> given to <tt class="xref c c-func docutils literal"><span class="pre">ez_create_window()</span></tt>
has to be declared as:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">on_event</span> <span class="p">(</span><span class="n">Ez_event</span> <span class="o">*</span><span class="n">ev</span><span class="p">);</span>
</pre></div>
</div>
</dd></dl>

<dl class="function">
<dt id="c.ez_window_get_id">
int <tt class="descname">ez_window_get_id</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em><big>)</big><a class="headerlink" href="#c.ez_window_get_id" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the window id as an <tt class="docutils literal"><span class="pre">int</span></tt>.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_window_destroy">
void <tt class="descname">ez_window_destroy</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em><big>)</big><a class="headerlink" href="#c.ez_window_destroy" title="Permalink to this definition">¶</a></dt>
<dd><p>Destroy window <tt class="docutils literal"><span class="pre">win</span></tt>.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_window_show">
void <tt class="descname">ez_window_show</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;val</em><big>)</big><a class="headerlink" href="#c.ez_window_show" title="Permalink to this definition">¶</a></dt>
<dd><p>Show (<tt class="docutils literal"><span class="pre">val</span> <span class="pre">=</span> <span class="pre">1</span></tt>) or hide (<tt class="docutils literal"><span class="pre">val</span> <span class="pre">=</span> <span class="pre">0</span></tt>) the window <tt class="docutils literal"><span class="pre">win</span></tt>.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_window_set_size">
void <tt class="descname">ez_window_set_size</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;w</em>, int<em>&nbsp;h</em><big>)</big><a class="headerlink" href="#c.ez_window_set_size" title="Permalink to this definition">¶</a></dt>
<dd><p>Change the size of the window.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_window_get_size">
void <tt class="descname">ez_window_get_size</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;*w</em>, int<em>&nbsp;*h</em><big>)</big><a class="headerlink" href="#c.ez_window_get_size" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve the window size.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_window_clear">
void <tt class="descname">ez_window_clear</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em><big>)</big><a class="headerlink" href="#c.ez_window_clear" title="Permalink to this definition">¶</a></dt>
<dd><p>Empty the window (with a white background) and initialize the drawing
parameters (color, width, font) to the default values.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_send_expose">
void <tt class="descname">ez_send_expose</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em><big>)</big><a class="headerlink" href="#c.ez_send_expose" title="Permalink to this definition">¶</a></dt>
<dd><p>Send an <tt class="docutils literal"><span class="pre">Expose</span></tt> event to the window, so as to empty the window and to
force to redraw.</p>
</dd></dl>

</div>
<div class="section" id="events">
<span id="sec-ref-events"></span><span id="index-4"></span><h2>2.3. Events<a class="headerlink" href="#events" title="Permalink to this headline">¶</a></h2>
<p>Each event is described by a struct of type <a class="reference internal" href="#c.Ez_event" title="Ez_event"><tt class="xref c c-type docutils literal"><span class="pre">Ez_event</span></tt></a>:</p>
<dl class="type">
<dt id="c.Ez_event">
<tt class="descname">Ez_event</tt><a class="headerlink" href="#c.Ez_event" title="Permalink to this definition">¶</a></dt>
<dd><p>Store an event.</p>
</dd></dl>

<p>This type is defined in <a class="reference external" href="../../../ez-draw.h">ez-draw.h</a> as follows:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
    <span class="kt">int</span> <span class="n">type</span><span class="p">;</span>                       <span class="cm">/* Expose, ButtonPress, etc                */</span>
    <span class="n">Ez_window</span> <span class="n">win</span><span class="p">;</span>                  <span class="cm">/* Identifier of the window                */</span>
    <span class="kt">int</span> <span class="n">mx</span><span class="p">,</span> <span class="n">my</span><span class="p">;</span>                     <span class="cm">/* Mouse coordinates                       */</span>
    <span class="kt">int</span> <span class="n">mb</span><span class="p">;</span>                         <span class="cm">/* Mouse button, 0 = none                  */</span>
    <span class="kt">int</span> <span class="n">width</span><span class="p">,</span> <span class="n">height</span><span class="p">;</span>              <span class="cm">/* Width and height                        */</span>
    <span class="n">KeySym</span> <span class="n">key_sym</span><span class="p">;</span>                 <span class="cm">/* Key symbol: XK_Space, XK_q, etc         */</span>
    <span class="kt">char</span>   <span class="n">key_name</span><span class="p">[</span><span class="mi">80</span><span class="p">];</span>            <span class="cm">/* For tracing: &quot;XK_Space&quot;, &quot;XK_q&quot;, ..     */</span>
    <span class="kt">char</span>   <span class="n">key_string</span><span class="p">[</span><span class="mi">80</span><span class="p">];</span>          <span class="cm">/* Corresponding string: &quot; &quot;, &quot;q&quot;, etc     */</span>
    <span class="kt">int</span>    <span class="n">key_count</span><span class="p">;</span>               <span class="cm">/* String length                           */</span>
    <span class="cm">/* Other fields private */</span>
<span class="p">}</span> <span class="n">Ez_event</span><span class="p">;</span>
</pre></div>
</div>
<p>The first field gives the event type. The possible values are:</p>
<table border="1" class="centrer nonsouligner encadrer docutils">
<colgroup>
<col width="35%" />
<col width="65%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">Expose</span></tt></td>
<td>The whole window must be redrawn.</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">ButtonPress</span></tt></td>
<td>Mouse button pressed.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">ButtonRelease</span></tt></td>
<td>Mouse button released.</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">MotionNotify</span></tt></td>
<td>Mouse moved.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">KeyPress</span></tt></td>
<td>Key pressed.</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">KeyRelease</span></tt></td>
<td>Key released.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">ConfigureNotify</span></tt></td>
<td>The window size has changed.</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">WindowClose</span></tt></td>
<td>The button &#8220;Close&#8221; was pressed.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">TimerNotify</span></tt></td>
<td>The timer has expired.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="colors">
<span id="sec-ref-colors"></span><span id="index-5"></span><h2>2.4. Colors<a class="headerlink" href="#colors" title="Permalink to this headline">¶</a></h2>
<p>Each color is denoted by an integer of type <tt class="docutils literal"><span class="pre">Ez_uint32</span></tt>.</p>
<dl class="function">
<dt id="c.ez_set_color">
void <tt class="descname">ez_set_color</tt><big>(</big>Ez_uint32<em>&nbsp;color</em><big>)</big><a class="headerlink" href="#c.ez_set_color" title="Permalink to this definition">¶</a></dt>
<dd><p>Store the color <tt class="docutils literal"><span class="pre">color</span></tt> for the next drawings, as well as for text displaying.</p>
</dd></dl>

<p>The following colors are predefined:
<tt class="docutils literal"><span class="pre">ez_black</span></tt>, <tt class="docutils literal"><span class="pre">ez_white</span></tt>, <tt class="docutils literal"><span class="pre">ez_grey</span></tt>, <tt class="docutils literal"><span class="pre">ez_red</span></tt>, <tt class="docutils literal"><span class="pre">ez_green</span></tt>, <tt class="docutils literal"><span class="pre">ez_blue</span></tt>,
<tt class="docutils literal"><span class="pre">ez_yellow</span></tt>, <tt class="docutils literal"><span class="pre">ez_cyan</span></tt>, <tt class="docutils literal"><span class="pre">ez_magenta</span></tt>.</p>
<p>Other colors can be obtained with these functions:</p>
<dl class="function">
<dt id="c.ez_get_RGB">
Ez_uint32 <tt class="descname">ez_get_RGB</tt><big>(</big>Ez_uint8<em>&nbsp;r</em>, Ez_uint8<em>&nbsp;g</em>, Ez_uint8<em>&nbsp;b</em><big>)</big><a class="headerlink" href="#c.ez_get_RGB" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a color computed according to the levels <tt class="docutils literal"><span class="pre">r,g,b</span></tt> given between 0 and 255.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_get_grey">
Ez_uint32 <tt class="descname">ez_get_grey</tt><big>(</big>Ez_uint8<em>&nbsp;g</em><big>)</big><a class="headerlink" href="#c.ez_get_grey" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a grey color computed according to the level <tt class="docutils literal"><span class="pre">g</span></tt> given between 0 and 255.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_get_HSV">
Ez_uint32 <tt class="descname">ez_get_HSV</tt><big>(</big>double<em>&nbsp;h</em>, double<em>&nbsp;s</em>, double<em>&nbsp;v</em><big>)</big><a class="headerlink" href="#c.ez_get_HSV" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a color defined in space Hue, Saturation, Value.</p>
</dd></dl>

<p><tt class="docutils literal"><span class="pre">h</span></tt> is an angle between 0 and 360 degrees which arbitrary represents pure colors;
<tt class="docutils literal"><span class="pre">s</span></tt> is saturation, between 0 and 1 ; <tt class="docutils literal"><span class="pre">v</span></tt> is the luminosity value,
between 0 and 1.
For more information, see
<a class="reference external" href="http://en.wikipedia.org/wiki/Hue/saturation/value">Hue Saturation Value</a>
in Wikipedia.</p>
<dl class="function">
<dt id="c.ez_HSV_to_RGB">
void <tt class="descname">ez_HSV_to_RGB</tt><big>(</big>double<em>&nbsp;h</em>, double<em>&nbsp;s</em>, double<em>&nbsp;v</em>, Ez_uint8<em>&nbsp;*r</em>, Ez_uint8<em>&nbsp;*g</em>, Ez_uint8<em>&nbsp;*b</em><big>)</big><a class="headerlink" href="#c.ez_HSV_to_RGB" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert a color from HSV to RGB.</p>
<p>The ranges are:
<tt class="docutils literal"><span class="pre">h</span></tt> between 0 and 360,
<tt class="docutils literal"><span class="pre">s</span></tt> and <tt class="docutils literal"><span class="pre">v</span></tt> between 0 and 1,
<tt class="docutils literal"><span class="pre">*r</span></tt>, <tt class="docutils literal"><span class="pre">*g</span></tt>, <tt class="docutils literal"><span class="pre">*b</span></tt> between 0 and 255.</p>
</dd></dl>

<p>As examples, see <a class="reference external" href="../../../demo-11.c">demo-11.c</a> and <a class="reference external" href="../../../demo-12.c">demo-12.c</a>.</p>
<p>These windows are obtained:</p>
<div class="centrer container">
<img alt="demo-11" src="http://pageperso.lif.univ-mrs.fr/~edouard.thiel/snap-EZ-Draw-1.2/snap-demo-11.png" />
<img alt="demo-12" src="http://pageperso.lif.univ-mrs.fr/~edouard.thiel/snap-EZ-Draw-1.2/snap-demo-12.png" />
</div>
</div>
<div class="section" id="drawings">
<span id="sec-ref-drawings"></span><span id="index-6"></span><h2>2.5. Drawings<a class="headerlink" href="#drawings" title="Permalink to this headline">¶</a></h2>
<p>The coordinates are relative to the Origin, which is the top left point
inside the window; <tt class="docutils literal"><span class="pre">x</span></tt> goes to the right and <tt class="docutils literal"><span class="pre">y</span></tt> goes down.</p>
<p>For rectangles and circles, <tt class="docutils literal"><span class="pre">x1,y1</span></tt> and <tt class="docutils literal"><span class="pre">y2,y2</span></tt> are the top left and
bottom right coordinates of the bounding box.
For points, line segments and triangles, the vertex coordinates are
expected.</p>
<p>The default color is black; it can be changed with <a class="reference internal" href="#c.ez_set_color" title="ez_set_color"><tt class="xref c c-func docutils literal"><span class="pre">ez_set_color()</span></tt></a>.</p>
<dl class="function">
<dt id="c.ez_draw_point">
void <tt class="descname">ez_draw_point</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;x1</em>, int<em>&nbsp;y1</em><big>)</big><a class="headerlink" href="#c.ez_draw_point" title="Permalink to this definition">¶</a></dt>
<dd><p>Draw a point.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_draw_line">
void <tt class="descname">ez_draw_line</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;x1</em>, int<em>&nbsp;y1</em>, int<em>&nbsp;x2</em>, int<em>&nbsp;y2</em><big>)</big><a class="headerlink" href="#c.ez_draw_line" title="Permalink to this definition">¶</a></dt>
<dd><p>Draw a line segment.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_draw_rectangle">
void <tt class="descname">ez_draw_rectangle</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;x1</em>, int<em>&nbsp;y1</em>, int<em>&nbsp;x2</em>, int<em>&nbsp;y2</em><big>)</big><a class="headerlink" href="#c.ez_draw_rectangle" title="Permalink to this definition">¶</a></dt>
<dd><p>Draw a rectangle.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_fill_rectangle">
void <tt class="descname">ez_fill_rectangle</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;x1</em>, int<em>&nbsp;y1</em>, int<em>&nbsp;x2</em>, int<em>&nbsp;y2</em><big>)</big><a class="headerlink" href="#c.ez_fill_rectangle" title="Permalink to this definition">¶</a></dt>
<dd><p>Fill a rectangle.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_draw_triangle">
void <tt class="descname">ez_draw_triangle</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;x1</em>, int<em>&nbsp;y1</em>, int<em>&nbsp;x2</em>, int<em>&nbsp;y2</em>, int<em>&nbsp;x3</em>, int<em>&nbsp;y3</em><big>)</big><a class="headerlink" href="#c.ez_draw_triangle" title="Permalink to this definition">¶</a></dt>
<dd><p>Draw a triangle.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_fill_triangle">
void <tt class="descname">ez_fill_triangle</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;x1</em>, int<em>&nbsp;y1</em>, int<em>&nbsp;x2</em>, int<em>&nbsp;y2</em>, int<em>&nbsp;x3</em>, int<em>&nbsp;y3</em><big>)</big><a class="headerlink" href="#c.ez_fill_triangle" title="Permalink to this definition">¶</a></dt>
<dd><p>Fill a triangle.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_draw_circle">
void <tt class="descname">ez_draw_circle</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;x1</em>, int<em>&nbsp;y1</em>, int<em>&nbsp;x2</em>, int<em>&nbsp;y2</em><big>)</big><a class="headerlink" href="#c.ez_draw_circle" title="Permalink to this definition">¶</a></dt>
<dd><p>Draw a circle.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_fill_circle">
void <tt class="descname">ez_fill_circle</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;x1</em>, int<em>&nbsp;y1</em>, int<em>&nbsp;x2</em>, int<em>&nbsp;y2</em><big>)</big><a class="headerlink" href="#c.ez_fill_circle" title="Permalink to this definition">¶</a></dt>
<dd><p>Fill a circle.</p>
</dd></dl>

<p>Drawings with <a class="reference internal" href="#c.ez_draw_point" title="ez_draw_point"><tt class="xref c c-func docutils literal"><span class="pre">ez_draw_point()</span></tt></a>, <a class="reference internal" href="#c.ez_draw_line" title="ez_draw_line"><tt class="xref c c-func docutils literal"><span class="pre">ez_draw_line()</span></tt></a>,
<a class="reference internal" href="#c.ez_draw_rectangle" title="ez_draw_rectangle"><tt class="xref c c-func docutils literal"><span class="pre">ez_draw_rectangle()</span></tt></a>, <a class="reference internal" href="#c.ez_draw_triangle" title="ez_draw_triangle"><tt class="xref c c-func docutils literal"><span class="pre">ez_draw_triangle()</span></tt></a>, <a class="reference internal" href="#c.ez_draw_circle" title="ez_draw_circle"><tt class="xref c c-func docutils literal"><span class="pre">ez_draw_circle()</span></tt></a>
have a default thickness of 1 pixel. It can be changed with:</p>
<dl class="function">
<dt id="c.ez_set_thick">
void <tt class="descname">ez_set_thick</tt><big>(</big>int<em>&nbsp;thick</em><big>)</big><a class="headerlink" href="#c.ez_set_thick" title="Permalink to this definition">¶</a></dt>
<dd><p>Set thickness <tt class="docutils literal"><span class="pre">thick</span></tt> (in pixels) for the next drawings.</p>
</dd></dl>

</div>
<div class="section" id="text-and-fonts">
<span id="sec-ref-fonts"></span><span id="index-7"></span><h2>2.6. Text and fonts<a class="headerlink" href="#text-and-fonts" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="c.ez_font_load">
int <tt class="descname">ez_font_load</tt><big>(</big>int<em>&nbsp;num</em>, const char<em>&nbsp;*name</em><big>)</big><a class="headerlink" href="#c.ez_font_load" title="Permalink to this definition">¶</a></dt>
<dd><p>Load the font <tt class="docutils literal"><span class="pre">name</span></tt> (e.g. <tt class="docutils literal"><span class="pre">&quot;6x13&quot;</span></tt>) and store it as the font
number <tt class="docutils literal"><span class="pre">num</span></tt>.</p>
<p>Return 0 on success, -1 on error.</p>
</dd></dl>

<p>The font number must be less than <tt class="docutils literal"><span class="pre">EZ_FONT_MAX</span></tt>.
Some fixed fonts are preloaded by default:</p>
<blockquote>
<div><ul class="simple">
<li>Font number 0: <tt class="docutils literal"><span class="pre">&quot;6x13&quot;</span></tt></li>
<li>Font number 1: <tt class="docutils literal"><span class="pre">&quot;8x16&quot;</span></tt></li>
<li>Font number 2: <tt class="docutils literal"><span class="pre">&quot;10x20&quot;</span></tt></li>
<li>Font number 3: <tt class="docutils literal"><span class="pre">&quot;12x24&quot;</span></tt></li>
</ul>
</div></blockquote>
<dl class="docutils">
<dt>Note:</dt>
<dd>On X11, the name can be in any fashion but must correspond to an existing
font. On Windows, the name must be in the form
<em>width</em><tt class="docutils literal"><span class="pre">x</span></tt><em>height</em> (a matching font of fixed size is obtained).</dd>
</dl>
<dl class="function">
<dt id="c.ez_set_nfont">
void <tt class="descname">ez_set_nfont</tt><big>(</big>int<em>&nbsp;num</em><big>)</big><a class="headerlink" href="#c.ez_set_nfont" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the font number <tt class="docutils literal"><span class="pre">num</span></tt> for the next text drawings.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_draw_text">
void <tt class="descname">ez_draw_text</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, Ez_Align<em>&nbsp;align</em>, int<em>&nbsp;x1</em>, int<em>&nbsp;y1</em>, const char<em>&nbsp;*format</em>, ...<big>)</big><a class="headerlink" href="#c.ez_draw_text" title="Permalink to this definition">¶</a></dt>
<dd><p>Display text; same usage as <tt class="docutils literal"><span class="pre">printf</span></tt>.</p>
</dd></dl>

<p>Example:</p>
<blockquote>
<div><div class="highlight-c"><div class="highlight"><pre><span class="n">ez_draw_text</span> <span class="p">(</span><span class="n">win</span><span class="p">,</span> <span class="n">EZ_TL</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="s">&quot;Width = %d</span><span class="se">\n</span><span class="s">Height = %d&quot;</span><span class="p">,</span> <span class="n">w</span><span class="p">,</span> <span class="n">h</span><span class="p">);</span>
</pre></div>
</div>
</div></blockquote>
<p>The coordinates <tt class="docutils literal"><span class="pre">x1,y1</span></tt> are relative to <tt class="docutils literal"><span class="pre">align</span></tt>,
which takes for values:</p>
<table border="1" class="centrer nonsouligner encadrer docutils">
<colgroup>
<col width="32%" />
<col width="35%" />
<col width="33%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">EZ_TL</span></tt> (Top Left)</td>
<td><tt class="docutils literal"><span class="pre">EZ_TC</span></tt> (Top Center)</td>
<td><tt class="docutils literal"><span class="pre">EZ_TR</span></tt> (Top Right)</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">EZ_ML</span></tt> (Middle Left)</td>
<td><tt class="docutils literal"><span class="pre">EZ_MC</span></tt> (Middle Center)</td>
<td><tt class="docutils literal"><span class="pre">EZ_MR</span></tt> (Middle Right)</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">EZ_BL</span></tt> (Bottom Left)</td>
<td><tt class="docutils literal"><span class="pre">EZ_BC</span></tt> (Bottom Center)</td>
<td><tt class="docutils literal"><span class="pre">EZ_BR</span></tt> (Bottom Right)</td>
</tr>
</tbody>
</table>
<p>The text is drawn over the current content of the window; you can also delete
the background at the same time (with white) using these values for <tt class="docutils literal"><span class="pre">align</span></tt>:</p>
<table border="1" class="centrer nonsouligner encadrer docutils">
<colgroup>
<col width="32%" />
<col width="34%" />
<col width="33%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">EZ_TLF</span></tt> (Top Left Filled)</td>
<td><tt class="docutils literal"><span class="pre">EZ_TCF</span></tt> (Top Center Filled)</td>
<td><tt class="docutils literal"><span class="pre">EZ_TRF</span></tt> (Top Right Filled)</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">EZ_MLF</span></tt> (Middle Left Filled)</td>
<td><tt class="docutils literal"><span class="pre">EZ_MCF</span></tt> (Middle Center Filled)</td>
<td><tt class="docutils literal"><span class="pre">EZ_MRF</span></tt> (Middle Right Filled)</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">EZ_BLF</span></tt> (Bottom Left Filled)</td>
<td><tt class="docutils literal"><span class="pre">EZ_BCF</span></tt> (Bottom Center Filled)</td>
<td><tt class="docutils literal"><span class="pre">EZ_BRF</span></tt> (Bottom Right Filled)</td>
</tr>
</tbody>
</table>
<dl class="docutils">
<dt>By default:</dt>
<dd><ul class="first last simple">
<li>the text is displayed using font number 0 (<tt class="docutils literal"><span class="pre">6x13</span></tt>);
it can be changed by <a class="reference internal" href="#c.ez_set_nfont" title="ez_set_nfont"><tt class="xref c c-func docutils literal"><span class="pre">ez_set_nfont()</span></tt></a>.</li>
<li>the text is displayed in black; the color can be changed with
<a class="reference internal" href="#c.ez_set_color" title="ez_set_color"><tt class="xref c c-func docutils literal"><span class="pre">ez_set_color()</span></tt></a>.</li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="double-buffering">
<span id="sec-ref-dbuf"></span><span id="index-8"></span><h2>2.7. Double buffering<a class="headerlink" href="#double-buffering" title="Permalink to this headline">¶</a></h2>
<p>Displaying with a double buffer prevents the window flashes while it is refreshed.
The idea is to draw in the double buffer, then swap it with the window content
when all the drawings are finished. Everything is handled automatically by EZ-Draw.</p>
<dl class="function">
<dt id="c.ez_window_dbuf">
void <tt class="descname">ez_window_dbuf</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;val</em><big>)</big><a class="headerlink" href="#c.ez_window_dbuf" title="Permalink to this definition">¶</a></dt>
<dd><p>Enable or disable the double buffer display for the window <tt class="docutils literal"><span class="pre">win</span></tt>.</p>
</dd></dl>

<p>By default, the double buffering is disabled (<tt class="docutils literal"><span class="pre">val</span> <span class="pre">=</span> <span class="pre">0</span></tt>).</p>
<p>If the double buffering is enabled (<tt class="docutils literal"><span class="pre">val</span> <span class="pre">=</span> <span class="pre">1</span></tt>) for a window,
every drawings in this window must be made during <tt class="docutils literal"><span class="pre">Expose</span></tt> events only.
If the double buffering is disabled,  it is no longer a requirement,
but it is strongly advised.</p>
<p>As an example, see in game <a class="reference external" href="../../../jeu-nim.c">jeu-nim.c</a> the functions
<tt class="docutils literal"><span class="pre">gui_init()</span></tt>, <tt class="docutils literal"><span class="pre">win1_onKeyPress()</span></tt>, <tt class="docutils literal"><span class="pre">win1_onExpose()</span></tt>.</p>
<p>In this game, you can test the display with or without the double buffer
(press key <tt class="docutils literal"><span class="pre">d</span></tt> to switch between one and the other):</p>
<div class="centrer container">
<img alt="jeu-nim-2" src="http://pageperso.lif.univ-mrs.fr/~edouard.thiel/snap-EZ-Draw-1.2/snap-jeu-nim-2.png" />
</div>
</div>
<div class="section" id="timers">
<span id="sec-ref-timers"></span><span id="index-9"></span><h2>2.8. Timers<a class="headerlink" href="#timers" title="Permalink to this headline">¶</a></h2>
<p><em>Starting a timer</em> means storing a date in the future, which is the current date
plus a certain delay. When we arrive at this date in the future, we say that the
timer has <em>expired</em>.</p>
<p>Each window can be associated with a timer.
Upon expiration of the timer, the program receives a unique event
<tt class="docutils literal"><span class="pre">TimerNotify</span></tt> for the window, then the timer is deleted.</p>
<dl class="function">
<dt id="c.ez_start_timer">
void <tt class="descname">ez_start_timer</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, int<em>&nbsp;delay</em><big>)</big><a class="headerlink" href="#c.ez_start_timer" title="Permalink to this definition">¶</a></dt>
<dd><p>Start a timer for the window <tt class="docutils literal"><span class="pre">win</span></tt> with the delay <tt class="docutils literal"><span class="pre">delay</span></tt> expressed
in milliseconds.</p>
</dd></dl>

<p>Any recall of this function before timer expiration will cancel and replace
the timer with the new delay. Moreover, if <tt class="docutils literal"><span class="pre">delay</span></tt> is <tt class="docutils literal"><span class="pre">-1</span></tt> then the timer
is deleted.
(Note: this is not an error to delete a timer already deleted or non-existent).</p>
<p>An an example, see <a class="reference external" href="../../../demo-09.c">demo-09.c</a>.</p>
</div>
<div class="section" id="client-data">
<span id="sec-ref-client-data"></span><span id="index-10"></span><h2>2.9. Client-data<a class="headerlink" href="#client-data" title="Permalink to this headline">¶</a></h2>
<p>Each window can store an arbitrary data of the program,
for instance a string or a struct address.
You can then recover the data at any time in the program.
This mechanism aims to avoid global variables.</p>
<dl class="function">
<dt id="c.ez_set_data">
void <tt class="descname">ez_set_data</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, void<em>&nbsp;*data</em><big>)</big><a class="headerlink" href="#c.ez_set_data" title="Permalink to this definition">¶</a></dt>
<dd><p>Store the data <tt class="docutils literal"><span class="pre">data</span></tt> in the window <tt class="docutils literal"><span class="pre">win</span></tt></p>
</dd></dl>

<dl class="function">
<dt id="c.ez_get_data">
void *<tt class="descname">ez_get_data</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em><big>)</big><a class="headerlink" href="#c.ez_get_data" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the data stored in the window <tt class="docutils literal"><span class="pre">win</span></tt>.</p>
</dd></dl>

<p>Here is an example of program that draws a circle, whose coordinates
are stored into a global variable <tt class="docutils literal"><span class="pre">md</span></tt>:</p>
<div class="highlight-c"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36</pre></div></td><td class="code"><div class="highlight"><pre><span class="cp">#include &quot;ez-draw.h&quot;</span>

<span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
    <span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">r</span><span class="p">;</span>
<span class="p">}</span> <span class="n">My_data</span><span class="p">;</span>

<span class="n">My_data</span> <span class="n">md</span><span class="p">;</span>  <span class="cm">/* 1. Global variable */</span>


<span class="kt">void</span> <span class="nf">win1_on_expose</span> <span class="p">(</span><span class="n">Ez_event</span> <span class="o">*</span><span class="n">ev</span><span class="p">)</span>
<span class="p">{</span>
    <span class="cm">/* 3. Use */</span>
    <span class="n">ez_draw_circle</span> <span class="p">(</span><span class="n">ev</span><span class="o">-&gt;</span><span class="n">win</span><span class="p">,</span> <span class="n">md</span><span class="p">.</span><span class="n">x</span><span class="o">-</span><span class="n">md</span><span class="p">.</span><span class="n">r</span><span class="p">,</span> <span class="n">md</span><span class="p">.</span><span class="n">y</span><span class="o">-</span><span class="n">md</span><span class="p">.</span><span class="n">r</span><span class="p">,</span> <span class="n">md</span><span class="p">.</span><span class="n">x</span><span class="o">+</span><span class="n">md</span><span class="p">.</span><span class="n">r</span><span class="p">,</span> <span class="n">md</span><span class="p">.</span><span class="n">y</span><span class="o">+</span><span class="n">md</span><span class="p">.</span><span class="n">r</span><span class="p">);</span>
<span class="p">}</span>


<span class="kt">void</span> <span class="nf">win1_on_event</span> <span class="p">(</span><span class="n">Ez_event</span> <span class="o">*</span><span class="n">ev</span><span class="p">)</span>
<span class="p">{</span>
   <span class="k">switch</span> <span class="p">(</span><span class="n">ev</span><span class="o">-&gt;</span><span class="n">type</span><span class="p">)</span> <span class="p">{</span>
        <span class="k">case</span> <span class="n">Expose</span> : <span class="n">win1_on_expose</span> <span class="p">(</span><span class="n">ev</span><span class="p">);</span> <span class="k">break</span><span class="p">;</span>
    <span class="p">}</span>
<span class="p">}</span>


<span class="kt">int</span> <span class="nf">main</span> <span class="p">()</span>
<span class="p">{</span>
    <span class="k">if</span> <span class="p">(</span><span class="n">ez_init</span><span class="p">()</span> <span class="o">&lt;</span> <span class="mi">0</span><span class="p">)</span> <span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>

    <span class="cm">/* 2. Initialization */</span>
    <span class="n">md</span><span class="p">.</span><span class="n">x</span> <span class="o">=</span> <span class="mi">200</span><span class="p">;</span> <span class="n">md</span><span class="p">.</span><span class="n">y</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span> <span class="n">md</span><span class="p">.</span><span class="n">r</span> <span class="o">=</span> <span class="mi">50</span><span class="p">;</span>

    <span class="n">ez_window_create</span> <span class="p">(</span><span class="mi">400</span><span class="p">,</span> <span class="mi">300</span><span class="p">,</span> <span class="s">&quot;Demo client-data 1&quot;</span><span class="p">,</span> <span class="n">win1_on_event</span><span class="p">);</span>

    <span class="n">ez_main_loop</span> <span class="p">();</span>
    <span class="n">exit</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</td></tr></table></div>
<p>Here is now the same program but without using global variable;
the data are stored in the window:</p>
<div class="highlight-c"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43</pre></div></td><td class="code"><div class="highlight"><pre><span class="cp">#include &quot;ez-draw.h&quot;</span>

<span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
    <span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">r</span><span class="p">;</span>
<span class="p">}</span> <span class="n">My_data</span><span class="p">;</span>


<span class="kt">void</span> <span class="nf">win1_on_expose</span> <span class="p">(</span><span class="n">Ez_event</span> <span class="o">*</span><span class="n">ev</span><span class="p">)</span>
<span class="p">{</span>
    <span class="cm">/* 4. We retrieve the data stored in the window */</span>
    <span class="n">My_data</span> <span class="o">*</span><span class="n">md</span> <span class="o">=</span> <span class="n">ez_get_data</span> <span class="p">(</span><span class="n">ev</span><span class="o">-&gt;</span><span class="n">win</span><span class="p">);</span>

    <span class="cm">/* 5. Use */</span>
    <span class="n">ez_draw_circle</span> <span class="p">(</span><span class="n">ev</span><span class="o">-&gt;</span><span class="n">win</span><span class="p">,</span> <span class="n">md</span><span class="o">-&gt;</span><span class="n">x</span><span class="o">-</span><span class="n">md</span><span class="o">-&gt;</span><span class="n">r</span><span class="p">,</span> <span class="n">md</span><span class="o">-&gt;</span><span class="n">y</span><span class="o">-</span><span class="n">md</span><span class="o">-&gt;</span><span class="n">r</span><span class="p">,</span> <span class="n">md</span><span class="o">-&gt;</span><span class="n">x</span><span class="o">+</span><span class="n">md</span><span class="o">-&gt;</span><span class="n">r</span><span class="p">,</span> <span class="n">md</span><span class="o">-&gt;</span><span class="n">y</span><span class="o">+</span><span class="n">md</span><span class="o">-&gt;</span><span class="n">r</span><span class="p">);</span>
<span class="p">}</span>


<span class="kt">void</span> <span class="nf">win1_on_event</span> <span class="p">(</span><span class="n">Ez_event</span> <span class="o">*</span><span class="n">ev</span><span class="p">)</span>
<span class="p">{</span>
   <span class="k">switch</span> <span class="p">(</span><span class="n">ev</span><span class="o">-&gt;</span><span class="n">type</span><span class="p">)</span> <span class="p">{</span>
        <span class="k">case</span> <span class="n">Expose</span> : <span class="n">win1_on_expose</span> <span class="p">(</span><span class="n">ev</span><span class="p">);</span> <span class="k">break</span><span class="p">;</span>
    <span class="p">}</span>
<span class="p">}</span>


<span class="kt">int</span> <span class="nf">main</span> <span class="p">()</span>
<span class="p">{</span>
    <span class="n">Ez_window</span> <span class="n">win1</span><span class="p">;</span>
    <span class="n">My_data</span> <span class="n">md</span><span class="p">;</span>  <span class="cm">/* 1. Local variable to main() */</span>

    <span class="k">if</span> <span class="p">(</span><span class="n">ez_init</span><span class="p">()</span> <span class="o">&lt;</span> <span class="mi">0</span><span class="p">)</span> <span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>

    <span class="cm">/* 2. Initialization */</span>
    <span class="n">md</span><span class="p">.</span><span class="n">x</span> <span class="o">=</span> <span class="mi">200</span><span class="p">;</span> <span class="n">md</span><span class="p">.</span><span class="n">y</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span> <span class="n">md</span><span class="p">.</span><span class="n">r</span> <span class="o">=</span> <span class="mi">50</span><span class="p">;</span>

    <span class="n">win1</span> <span class="o">=</span> <span class="n">ez_window_create</span> <span class="p">(</span><span class="mi">400</span><span class="p">,</span> <span class="mi">300</span><span class="p">,</span> <span class="s">&quot;Demo client-data 2&quot;</span><span class="p">,</span> <span class="n">win1_on_event</span><span class="p">);</span>

    <span class="cm">/* 3. We store the data in the window */</span>
    <span class="n">ez_set_data</span> <span class="p">(</span><span class="n">win1</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">md</span><span class="p">);</span>

    <span class="n">ez_main_loop</span> <span class="p">();</span>
    <span class="n">exit</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</td></tr></table></div>
<p>As another example, see <a class="reference external" href="../../../demo-10.c">demo-10.c</a>.</p>
</div>
<div class="section" id="the-image-type">
<span id="sec-ref-images-type"></span><span id="index-11"></span><h2>2.10. The image type<a class="headerlink" href="#the-image-type" title="Permalink to this headline">¶</a></h2>
<p>EZ-Draw allows to display or to manipulate images, thanks to the type:</p>
<dl class="type">
<dt id="c.Ez_image">
<tt class="descname">Ez_image</tt><a class="headerlink" href="#c.Ez_image" title="Permalink to this definition">¶</a></dt>
<dd><p>Main <tt class="docutils literal"><span class="pre">struct</span></tt> type to store an image.</p>
</dd></dl>

<p>This type is defined in <a class="reference external" href="../../../ez-image.h">ez-image.h</a> as follows:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
    <span class="kt">int</span> <span class="n">width</span><span class="p">,</span> <span class="n">height</span><span class="p">;</span>
    <span class="n">Ez_uint8</span> <span class="o">*</span><span class="n">pixels_rgba</span><span class="p">;</span>
    <span class="kt">int</span> <span class="n">has_alpha</span><span class="p">;</span>
    <span class="kt">int</span> <span class="n">opacity</span><span class="p">;</span>
<span class="p">}</span> <span class="n">Ez_image</span><span class="p">;</span>
</pre></div>
</div>
<p>Guess what: the image width in pixels is <tt class="docutils literal"><span class="pre">width</span></tt> and its height is <tt class="docutils literal"><span class="pre">height</span></tt>.</p>
<p>The pixels are stored in the table <tt class="docutils literal"><span class="pre">pixels_rgba</span></tt>
as R,G,B,A (for red, green, blue and alpha, that is to say transparency)
each having a value between 0 and 255 (255 is the maximum intensity or opacity).</p>
<p>The R,G,B,A values of a pixel having coordinates <tt class="docutils literal"><span class="pre">x,y</span></tt> in the image
are stored in <tt class="docutils literal"><span class="pre">pixels_rgba[(y*width+x)*4</span> <span class="pre">+</span> <span class="pre">0..3]</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">has_alpha</span></tt> field indicates if the alpha channel is used (<tt class="docutils literal"><span class="pre">has_alpha</span> <span class="pre">=</span> <span class="pre">1</span></tt>)
or ignored (<tt class="docutils literal"><span class="pre">has_alpha</span> <span class="pre">=</span> <span class="pre">0</span></tt>) when displaying.
If the channel is ignored, all pixels are displayed;
if used, just the opaque pixels are displayed.</p>
<p>The opaque pixels are those for which the alpha channel is greater or equal
to the opacity threshold, specified by the <tt class="docutils literal"><span class="pre">opacity</span></tt> field;
by default, the opacity threshold is 128.</p>
<dl class="docutils">
<dt><strong>Warning:</strong></dt>
<dd>do not modified the fields <tt class="docutils literal"><span class="pre">width</span></tt>, <tt class="docutils literal"><span class="pre">height</span></tt>, <tt class="docutils literal"><span class="pre">pixels_rgba</span></tt> of an
image, since they describe the allocated memory.
However, you can change the fields <tt class="docutils literal"><span class="pre">has_alpha</span></tt>, <tt class="docutils literal"><span class="pre">opacity</span></tt>,
as well as the pixel values in <tt class="docutils literal"><span class="pre">pixels_rgba[]</span></tt>.
You may also use the following functions.</dd>
</dl>
<dl class="function">
<dt id="c.ez_image_set_alpha">
void <tt class="descname">ez_image_set_alpha</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em>, int<em>&nbsp;has_alpha</em><big>)</big><a class="headerlink" href="#c.ez_image_set_alpha" title="Permalink to this definition">¶</a></dt>
<dt id="c.ez_image_has_alpha">
int  <tt class="descname">ez_image_has_alpha</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em><big>)</big><a class="headerlink" href="#c.ez_image_has_alpha" title="Permalink to this definition">¶</a></dt>
<dt id="c.ez_image_set_opacity">
void <tt class="descname">ez_image_set_opacity</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em>, int<em>&nbsp;opacity</em><big>)</big><a class="headerlink" href="#c.ez_image_set_opacity" title="Permalink to this definition">¶</a></dt>
<dt id="c.ez_image_get_opacity">
int  <tt class="descname">ez_image_get_opacity</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em><big>)</big><a class="headerlink" href="#c.ez_image_get_opacity" title="Permalink to this definition">¶</a></dt>
<dd><p>Get back or change the fields <tt class="docutils literal"><span class="pre">has_alpha</span></tt> and <tt class="docutils literal"><span class="pre">opacity</span></tt>.</p>
<p>These functions simply do nothing if <tt class="docutils literal"><span class="pre">img</span></tt> is <tt class="docutils literal"><span class="pre">NULL</span></tt>.</p>
</dd></dl>

</div>
<div class="section" id="managing-images">
<span id="sec-ref-managing-images"></span><span id="index-12"></span><h2>2.11. Managing images<a class="headerlink" href="#managing-images" title="Permalink to this headline">¶</a></h2>
<p>To use the following functions you must include <a class="reference external" href="../../../ez-image.h">ez-image.h</a>.</p>
<dl class="function">
<dt id="c.ez_image_create">
<a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a> *<tt class="descname">ez_image_create</tt><big>(</big>int<em>&nbsp;w</em>, int<em>&nbsp;h</em><big>)</big><a class="headerlink" href="#c.ez_image_create" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an image having width <tt class="docutils literal"><span class="pre">w</span></tt> and height <tt class="docutils literal"><span class="pre">h</span></tt>, in pixels.</p>
<p>Return the created image, or <tt class="docutils literal"><span class="pre">NULL</span></tt> on error.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_image_load">
<a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a> *<tt class="descname">ez_image_load</tt><big>(</big>const char<em>&nbsp;*filename</em><big>)</big><a class="headerlink" href="#c.ez_image_load" title="Permalink to this definition">¶</a></dt>
<dd><p>Load an image from the file <tt class="docutils literal"><span class="pre">filename</span></tt>.
The file must be in PNG, JPEG, GIF or BMP format.</p>
<p>Transparency is supported for PNG, GIF and BMP format:
if the file contains an alpha channel, then the field <tt class="docutils literal"><span class="pre">has_alpha</span></tt>
of the image is set to 1.</p>
<p>Return the created image, or <tt class="docutils literal"><span class="pre">NULL</span></tt> on error.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_image_dup">
<a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a> *<tt class="descname">ez_image_dup</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em><big>)</big><a class="headerlink" href="#c.ez_image_dup" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a deep copy of the image <tt class="docutils literal"><span class="pre">img</span></tt>.</p>
<p>Return the created image, or <tt class="docutils literal"><span class="pre">NULL</span></tt> on error.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_image_destroy">
void <tt class="descname">ez_image_destroy</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em><big>)</big><a class="headerlink" href="#c.ez_image_destroy" title="Permalink to this definition">¶</a></dt>
<dd><p>Destroy an image in memory.</p>
<p>All images created by <tt class="docutils literal"><span class="pre">ez_image_...</span></tt> should be destroyed using this function.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_image_paint">
void <tt class="descname">ez_image_paint</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, <a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em>, int<em>&nbsp;x</em>, int<em>&nbsp;y</em><big>)</big><a class="headerlink" href="#c.ez_image_paint" title="Permalink to this definition">¶</a></dt>
<dd><p>Display an image in the window <tt class="docutils literal"><span class="pre">win</span></tt>, with the upper left corner of the image
at the <tt class="docutils literal"><span class="pre">x,y</span></tt> coordinates in the window.
If <tt class="docutils literal"><span class="pre">img-&gt;has_alpha</span></tt> is true, apply transparency, that is to say,
only display opaque pixels.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_image_paint_sub">
void <tt class="descname">ez_image_paint_sub</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, <a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em>, int<em>&nbsp;x</em>, int<em>&nbsp;y</em>, int<em>&nbsp;src_x</em>, int<em>&nbsp;src_y</em>, int<em>&nbsp;w</em>, int<em>&nbsp;h</em><big>)</big><a class="headerlink" href="#c.ez_image_paint_sub" title="Permalink to this definition">¶</a></dt>
<dd><p>Display a rectangular region of an image in the window <tt class="docutils literal"><span class="pre">win</span></tt>.</p>
<p>The image region is bounded by coordinates <tt class="docutils literal"><span class="pre">src_x,</span> <span class="pre">src_y</span></tt>
(top left corner) and <tt class="docutils literal"><span class="pre">src_x+w-1,</span> <span class="pre">src_y+h-1</span></tt> (bottom right corner)
in the image. If the coordinates go beyond the image, just the region
which actually fits in the image is displayed.</p>
<p>The top left corner of the region is displayed at the <tt class="docutils literal"><span class="pre">x,y</span></tt>
coordinate in the window.
If <tt class="docutils literal"><span class="pre">img-&gt;has_alpha</span></tt> is true, apply transparency.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_image_print">
void <tt class="descname">ez_image_print</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em>, int<em>&nbsp;src_x</em>, int<em>&nbsp;src_y</em>, int<em>&nbsp;w</em>, int<em>&nbsp;h</em><big>)</big><a class="headerlink" href="#c.ez_image_print" title="Permalink to this definition">¶</a></dt>
<dd><p>Display a rectangular region of an image in the terminal.</p>
<p>The image region is bounded by coordinates <tt class="docutils literal"><span class="pre">src_x,</span> <span class="pre">src_y</span></tt>
(top left corner) and <tt class="docutils literal"><span class="pre">src_x+w-1,</span> <span class="pre">src_y+h-1</span></tt> (bottom right corner)
in the image. If the coordinates go beyond the image, just the region
which actually fits in the image is displayed.</p>
</dd></dl>

</div>
<div class="section" id="operations-on-images">
<span id="sec-ref-oper-on-images"></span><span id="index-13"></span><h2>2.12. Operations on images<a class="headerlink" href="#operations-on-images" title="Permalink to this headline">¶</a></h2>
<p>This section presents some operations which are available by including
<a class="reference external" href="../../../ez-image.h">ez-image.h</a>.
These operations are done on colors and on the alpha channel.</p>
<dl class="function">
<dt id="c.ez_image_fill_rgba">
void <tt class="descname">ez_image_fill_rgba</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em>, Ez_uint8<em>&nbsp;r</em>, Ez_uint8<em>&nbsp;g</em>, Ez_uint8<em>&nbsp;b</em>, Ez_uint8<em>&nbsp;a</em><big>)</big><a class="headerlink" href="#c.ez_image_fill_rgba" title="Permalink to this definition">¶</a></dt>
<dd><p>Fill an image with color <tt class="docutils literal"><span class="pre">r,g,b,a</span></tt>.</p>
<p>The values are between 0 and 255.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_image_blend">
void <tt class="descname">ez_image_blend</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*dst</em>, <a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*src</em>, int<em>&nbsp;dst_x</em>, int<em>&nbsp;dst_y</em><big>)</big><a class="headerlink" href="#c.ez_image_blend" title="Permalink to this definition">¶</a></dt>
<dt id="c.ez_image_blend_sub">
void <tt class="descname">ez_image_blend_sub</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*dst</em>, <a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*src</em>, int<em>&nbsp;dst_x</em>, int<em>&nbsp;dst_y</em>, int<em>&nbsp;src_x</em>, int<em>&nbsp;src_y</em>, int<em>&nbsp;w</em>, int<em>&nbsp;h</em><big>)</big><a class="headerlink" href="#c.ez_image_blend_sub" title="Permalink to this definition">¶</a></dt>
<dd><p>Superimpose a region of image <tt class="docutils literal"><span class="pre">src</span></tt> into the image <tt class="docutils literal"><span class="pre">dst</span></tt>.</p>
<p>The region of source image <tt class="docutils literal"><span class="pre">src</span></tt> is bounded by coordinates
<tt class="docutils literal"><span class="pre">src_x,</span> <span class="pre">src_y</span></tt> (top left corner) and <tt class="docutils literal"><span class="pre">src_x+w-1,</span> <span class="pre">src_y+h-1</span></tt>
(bottom right corner).
The function superimposes this region into the destination image <tt class="docutils literal"><span class="pre">dst</span></tt>
at coordinates <tt class="docutils literal"><span class="pre">dst_x,</span> <span class="pre">dst_y</span></tt> (top left corner) and
<tt class="docutils literal"><span class="pre">dst_x+w-1,</span> <span class="pre">dst_y+h-1</span></tt> (bottom right corner).</p>
<p>If the coordinates go beyond the images <tt class="docutils literal"><span class="pre">src</span></tt> or <tt class="docutils literal"><span class="pre">dst</span></tt>,
just the common region is superimposed.
If the source image has no alpha channel (<tt class="docutils literal"><span class="pre">src-&gt;has_alpha</span></tt>
is false), then the pixel values from the <tt class="docutils literal"><span class="pre">src</span></tt> region
overwrite those of <tt class="docutils literal"><span class="pre">dst</span></tt>.
Otherwise, the regions are melted by transparency
(<em>alpha blending</em>) using formulas of
<a class="reference external" href="http://fr.wikipedia.org/wiki/Alpha_blending">Porter and Duff</a>.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_image_extract">
<a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a> *<tt class="descname">ez_image_extract</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em>, int<em>&nbsp;src_x</em>, int<em>&nbsp;src_y</em>, int<em>&nbsp;w</em>, int<em>&nbsp;h</em><big>)</big><a class="headerlink" href="#c.ez_image_extract" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an image containing a copy of a rectangular region of the
source image <tt class="docutils literal"><span class="pre">img</span></tt>.</p>
<p>The region of the image is bounded by coordinates <tt class="docutils literal"><span class="pre">src_x,</span> <span class="pre">src_y</span></tt>
(top left corner) and <tt class="docutils literal"><span class="pre">src_x+w-1,</span> <span class="pre">src_y+h-1</span></tt> (bottom right corner)
in <tt class="docutils literal"><span class="pre">img</span></tt>. If the coordinates go beyond the image, just the region
fitting in the image is extracted.</p>
<p>Return <tt class="docutils literal"><span class="pre">NULL</span></tt> on memory error or if intersection is empty.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_image_sym_ver">
<a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a> *<tt class="descname">ez_image_sym_ver</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em><big>)</big><a class="headerlink" href="#c.ez_image_sym_ver" title="Permalink to this definition">¶</a></dt>
<dt id="c.ez_image_sym_hor">
<a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a> *<tt class="descname">ez_image_sym_hor</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em><big>)</big><a class="headerlink" href="#c.ez_image_sym_hor" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an image of same size and properties as the source image <tt class="docutils literal"><span class="pre">img</span></tt>,
containing the symmetrical image with respect to the vertical or horizontal axis.</p>
<p>Return the new image, or <tt class="docutils literal"><span class="pre">NULL</span></tt> on error.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_image_scale">
<a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a> *<tt class="descname">ez_image_scale</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em>, double<em>&nbsp;factor</em><big>)</big><a class="headerlink" href="#c.ez_image_scale" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an image whose size is scaled by the <tt class="docutils literal"><span class="pre">factor</span></tt> with respect to
the source image <tt class="docutils literal"><span class="pre">img</span></tt>, containing the rescaled image.
The scale factor <tt class="docutils literal"><span class="pre">factor</span></tt> must be strictly positive.</p>
<p>Return the new image, or <tt class="docutils literal"><span class="pre">NULL</span></tt> on error.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_image_rotate">
<a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a> *<tt class="descname">ez_image_rotate</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em>, double<em>&nbsp;theta</em>, int<em>&nbsp;quality</em><big>)</big><a class="headerlink" href="#c.ez_image_rotate" title="Permalink to this definition">¶</a></dt>
<dd><p>Compute a rotation of the source image <tt class="docutils literal"><span class="pre">img</span></tt> for angle <tt class="docutils literal"><span class="pre">theta</span></tt>, in degrees.
Return a new image whose size is adjusted to contain the result, or <tt class="docutils literal"><span class="pre">NULL</span></tt>
on error.</p>
<p>In the resulting image, the field <tt class="docutils literal"><span class="pre">has_alpha</span></tt> is set to 1, and the parts
not coming from the source image are transparent, in such a manner that they
will not appear when displaying.</p>
<p>If <tt class="docutils literal"><span class="pre">quality</span> <span class="pre">=</span> <span class="pre">1</span></tt>, the function smooths the result (with a bi-linear
interpolation); if <tt class="docutils literal"><span class="pre">quality</span> <span class="pre">=</span> <span class="pre">0</span></tt>, the function focuses on speed (using a
closest neighbour computation), which saves a factor about 3.</p>
</dd></dl>

<dl class="docutils">
<dt>Note :</dt>
<dd>the result being independent from the rotation center, it is not required
as a parameter; however you can separately choose a rotation center and
compute its coordinates in the destination image, thanks to the
following function:</dd>
</dl>
<dl class="function">
<dt id="c.ez_image_rotate_point">
void <tt class="descname">ez_image_rotate_point</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em>, double<em>&nbsp;theta</em>, int<em>&nbsp;src_x</em>, int<em>&nbsp;src_y</em>, int<em>&nbsp;*dst_x</em>, int<em>&nbsp;*dst_y</em><big>)</big><a class="headerlink" href="#c.ez_image_rotate_point" title="Permalink to this definition">¶</a></dt>
<dd><p>Compute for a point having coordinates <tt class="docutils literal"><span class="pre">src_x,src_y</span></tt> in the source image,
the corresponding coordinates <tt class="docutils literal"><span class="pre">dst_x,dst_y</span></tt> of the point in the
destination image.</p>
</dd></dl>

<p>The example <a class="reference external" href="../../../demo-16.c">demo-16.c</a> illustrates rotations, with or without transparency.
The rotation center (red cross) is movable with the arrow keys. You can
even modify quality.</p>
<p>These windows are obtained:</p>
<div class="centrer container">
<img alt="demo-16-1" src="http://pageperso.lif.univ-mrs.fr/~edouard.thiel/snap-EZ-Draw-1.2/snap-demo-16-1.png" />
<img alt="demo-16-2" src="http://pageperso.lif.univ-mrs.fr/~edouard.thiel/snap-EZ-Draw-1.2/snap-demo-16-2.png" />
<img alt="demo-16-3" src="http://pageperso.lif.univ-mrs.fr/~edouard.thiel/snap-EZ-Draw-1.2/snap-demo-16-3.png" />
</div>
</div>
<div class="section" id="speed-up-image-display">
<span id="sec-ref-pixmaps"></span><span id="index-14"></span><h2>2.13. Speed up image display<a class="headerlink" href="#speed-up-image-display" title="Permalink to this headline">¶</a></h2>
<p>We have seen in the previous sections the type <a class="reference internal" href="#c.Ez_image" title="Ez_image"><tt class="xref c c-type docutils literal"><span class="pre">Ez_image</span></tt></a> defined
in <a class="reference external" href="../../../ez-image.h">ez-image.h</a>.</p>
<p>This type is convenient for loading, transforming and displaying images.
However, displaying an image takes a few milliseconds to a few tens
of milliseconds, this duration varying with the image size and computer power.</p>
<p>The reason is that for each display, <a class="reference internal" href="#c.ez_image_paint" title="ez_image_paint"><tt class="xref c c-func docutils literal"><span class="pre">ez_image_paint()</span></tt></a> computes again
the whole conversion from the type <a class="reference internal" href="#c.Ez_image" title="Ez_image"><tt class="xref c c-type docutils literal"><span class="pre">Ez_image</span></tt></a>, to an intermediate
image in memory, applies the transparency if needed, sends the result
to the graphic card, which finally displays it.</p>
<p>We can trace the duration of operations in the terminal, by setting an
environment variable then running one of the demonstration programs:
on Unix, type</p>
<div class="highlight-console"><div class="highlight"><pre><span class="go">export EZ_IMAGE_DEBUG=1</span>
</pre></div>
</div>
<p>or on Windows, type:</p>
<div class="highlight-console"><div class="highlight"><pre><span class="go">set EZ_IMAGE_DEBUG=1</span>
</pre></div>
</div>
<p>We obtain this for instance on Unix:</p>
<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> ./demo-14
<span class="go">ez_image_load  file &quot;images/paper1.jpg&quot;  in 8.725 ms  w = 640  h = 480  n = 3  has_alpha = 0</span>
<span class="go">ez_image_load  file &quot;images/tux1.png&quot;  in 1.946 ms  w = 210  h = 214  n = 4  has_alpha = 1</span>
<span class="go">ez_xi_create  w = 640  h = 480  depth = 24  bpp = 32</span>
<span class="go">ez_xi_fill_24 2.875 ms</span>
<span class="go">ez_xi_create  w = 210  h = 214  depth = 24  bpp = 32</span>
<span class="go">ez_xi_fill_24 0.132 ms</span>
<span class="go">ez_xmask_create   fill 0.119 ms   bitmap 5.610 ms</span>
</pre></div>
</div>
<p>To cancel this environment variable on Unix, type:</p>
<div class="highlight-console"><div class="highlight"><pre><span class="go">unset EZ_IMAGE_DEBUG</span>
</pre></div>
</div>
<p>or on Windows, type:</p>
<div class="highlight-console"><div class="highlight"><pre><span class="go">set EZ_IMAGE_DEBUG=</span>
</pre></div>
</div>
<p id="index-15">In an animation, all these times add up, and when there are a lot of images,
the animation may be jerky.
The solution is simple: convert the image of type <a class="reference internal" href="#c.Ez_image" title="Ez_image"><tt class="xref c c-type docutils literal"><span class="pre">Ez_image</span></tt></a>
as a pixmap of type <a class="reference internal" href="#c.Ez_pixmap" title="Ez_pixmap"><tt class="xref c c-type docutils literal"><span class="pre">Ez_pixmap</span></tt></a>, then display the pixmap.</p>
<dl class="type">
<dt id="c.Ez_pixmap">
typedef struct <tt class="descname">Ez_pixmap</tt><a class="headerlink" href="#c.Ez_pixmap" title="Permalink to this definition">¶</a></dt>
<dd><p>A pixmap is an image already converted and stored in the graphic card.
Its display is way faster, and also relieves the processor of the machine.</p>
<p>Once created, a pixmap is immutable.</p>
</dd></dl>

<p>This solution is also interesting to display a background image
(which size is often large). In this case, we can also gain efficiency by
using an image without alpha channel.</p>
<p>The type <a class="reference internal" href="#c.Ez_pixmap" title="Ez_pixmap"><tt class="xref c c-type docutils literal"><span class="pre">Ez_pixmap</span></tt></a> is defined as:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
    <span class="kt">int</span> <span class="n">width</span><span class="p">,</span> <span class="n">height</span><span class="p">;</span>
    <span class="cm">/* other fields private */</span>
<span class="p">}</span> <span class="n">Ez_pixmap</span>
</pre></div>
</div>
<p>The following functions handle pixmaps:</p>
<dl class="function">
<dt id="c.ez_pixmap_create_from_image">
<a class="reference internal" href="#c.Ez_pixmap" title="Ez_pixmap">Ez_pixmap</a> *<tt class="descname">ez_pixmap_create_from_image</tt><big>(</big><a class="reference internal" href="#c.Ez_image" title="Ez_image">Ez_image</a><em>&nbsp;*img</em><big>)</big><a class="headerlink" href="#c.ez_pixmap_create_from_image" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a pixmap from an image <tt class="docutils literal"><span class="pre">img</span></tt>.
The pixmap keeps the image transparency.
The image can then be freed if no longer needed.</p>
<p>Return the new pixmap, or <tt class="docutils literal"><span class="pre">NULL</span></tt> on error.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_pixmap_destroy">
void <tt class="descname">ez_pixmap_destroy</tt><big>(</big><a class="reference internal" href="#c.Ez_pixmap" title="Ez_pixmap">Ez_pixmap</a><em>&nbsp;*pix</em><big>)</big><a class="headerlink" href="#c.ez_pixmap_destroy" title="Permalink to this definition">¶</a></dt>
<dd><p>Delete the pixmap <tt class="docutils literal"><span class="pre">pix</span></tt>.</p>
<p>All pixmaps must be freed by this function.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_pixmap_paint">
void <tt class="descname">ez_pixmap_paint</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, <a class="reference internal" href="#c.Ez_pixmap" title="Ez_pixmap">Ez_pixmap</a><em>&nbsp;*pix</em>, int<em>&nbsp;x</em>, int<em>&nbsp;y</em><big>)</big><a class="headerlink" href="#c.ez_pixmap_paint" title="Permalink to this definition">¶</a></dt>
<dd><p>Display the pixmap <tt class="docutils literal"><span class="pre">pix</span></tt> in the window <tt class="docutils literal"><span class="pre">win</span></tt>.</p>
<p>The top left corner of the pixmap is displayed at the <tt class="docutils literal"><span class="pre">x,y</span></tt> coordinates
in the window.</p>
</dd></dl>

<dl class="function">
<dt id="c.ez_pixmap_tile">
void <tt class="descname">ez_pixmap_tile</tt><big>(</big><a class="reference internal" href="#c.Ez_window" title="Ez_window">Ez_window</a><em>&nbsp;win</em>, <a class="reference internal" href="#c.Ez_pixmap" title="Ez_pixmap">Ez_pixmap</a><em>&nbsp;*pix</em>, int<em>&nbsp;x</em>, int<em>&nbsp;y</em>, int<em>&nbsp;w</em>, int<em>&nbsp;h</em><big>)</big><a class="headerlink" href="#c.ez_pixmap_tile" title="Permalink to this definition">¶</a></dt>
<dd><p>Display the pixmap <tt class="docutils literal"><span class="pre">pix</span></tt> repeatedly in the window <tt class="docutils literal"><span class="pre">win</span></tt>.</p>
<p>The pixmap is displayed as a wallpaper in the window region bounded
by coordinates <tt class="docutils literal"><span class="pre">x,y</span></tt> (top left corner) and
<tt class="docutils literal"><span class="pre">x+w-1,y+h-1</span></tt> (bottom right corner).</p>
</dd></dl>

<p>The example <a class="reference external" href="../../../demo-17.c">demo-17.c</a> allows to check the display speed, measured in fps
(<em>frame per second</em>) in an animation.
Use keys <tt class="docutils literal"><span class="pre">+</span></tt> and <tt class="docutils literal"><span class="pre">-</span></tt> to change the number of balls,
and key <tt class="docutils literal"><span class="pre">p</span></tt> to enable or disable the use of pixmaps.</p>
<p>This window is obtained:</p>
<div class="centrer container">
<img alt="demo-17" src="http://pageperso.lif.univ-mrs.fr/~edouard.thiel/snap-EZ-Draw-1.2/snap-demo-17.png" />
</div>
</div>
<div class="section" id="miscellaneous">
<span id="sec-ref-misc"></span><h2>2.14. Miscellaneous<a class="headerlink" href="#miscellaneous" title="Permalink to this headline">¶</a></h2>
<span class="target" id="index-16"></span><dl class="function">
<dt id="c.ez_random">
int <tt class="descname">ez_random</tt><big>(</big>int<em>&nbsp;n</em><big>)</big><a class="headerlink" href="#c.ez_random" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a random integer between 0 and <tt class="docutils literal"><span class="pre">n-1</span></tt>.</p>
</dd></dl>

<p>Note: the random generator is initialized by <a class="reference internal" href="#c.ez_init" title="ez_init"><tt class="xref c c-func docutils literal"><span class="pre">ez_init()</span></tt></a>.</p>
<span class="target" id="index-17"></span><dl class="function">
<dt id="c.ez_get_time">
double <tt class="descname">ez_get_time</tt><big>(</big><big>)</big><a class="headerlink" href="#c.ez_get_time" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the time elapsed since the <em>Epoch</em> (1970, january the 1st at 0:00:00) in
seconds, with a precision in microseconds.</p>
</dd></dl>

<p>This function is usefull for measuring the duration of computations: just call
<a class="reference internal" href="#c.ez_get_time" title="ez_get_time"><tt class="xref c c-func docutils literal"><span class="pre">ez_get_time()</span></tt></a> before and after the computation, and then display the
difference:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">double</span> <span class="n">t1</span><span class="p">,</span> <span class="n">t2</span><span class="p">;</span>
<span class="n">t1</span> <span class="o">=</span> <span class="n">ez_get_time</span> <span class="p">();</span>
<span class="n">my_computation</span> <span class="p">();</span>
<span class="n">t2</span> <span class="o">=</span> <span class="n">ez_get_time</span> <span class="p">();</span>
<span class="n">printf</span> <span class="p">(</span><span class="s">&quot;Duration: %.6f s</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span> <span class="n">t2</span><span class="o">-</span><span class="n">t1</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper"><p class="quicklinks">
  <a href="../../../index-en.html">Back</a> |
  <a href="#">Up</a> |
  <a href="#endpage">Down</a>
</p>
<h3><a href="ez-manual.html">Table Of Contents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="ez-tutorial.html">1. Tutorial</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">2. Reference manual</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#main-loop">2.1. Main loop</a></li>
<li class="toctree-l2"><a class="reference internal" href="#windows">2.2. Windows</a></li>
<li class="toctree-l2"><a class="reference internal" href="#events">2.3. Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="#colors">2.4. Colors</a></li>
<li class="toctree-l2"><a class="reference internal" href="#drawings">2.5. Drawings</a></li>
<li class="toctree-l2"><a class="reference internal" href="#text-and-fonts">2.6. Text and fonts</a></li>
<li class="toctree-l2"><a class="reference internal" href="#double-buffering">2.7. Double buffering</a></li>
<li class="toctree-l2"><a class="reference internal" href="#timers">2.8. Timers</a></li>
<li class="toctree-l2"><a class="reference internal" href="#client-data">2.9. Client-data</a></li>
<li class="toctree-l2"><a class="reference internal" href="#the-image-type">2.10. The image type</a></li>
<li class="toctree-l2"><a class="reference internal" href="#managing-images">2.11. Managing images</a></li>
<li class="toctree-l2"><a class="reference internal" href="#operations-on-images">2.12. Operations on images</a></li>
<li class="toctree-l2"><a class="reference internal" href="#speed-up-image-display">2.13. Speed up image display</a></li>
<li class="toctree-l2"><a class="reference internal" href="#miscellaneous">2.14. Miscellaneous</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ez-install.html">3. Installation</a></li>
</ul>
<h3 class="indexlink">
  <a href="genindex.html#">Index</a>
</h3>

<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <span class="current">English</span></li>
        <li class="right">
          <a href="../../fr/html/ez-reference.html">Français</a> |</li>
        <li><a href="../../../index-en.html">EZ-Draw 1.2</a> &raquo;</li>
        <li><a href="ez-manual.html">Documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2014, Edouard Thiel.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
    </div>
    <a name="endpage"></a>
  </body>
</html>